.. _external_simulation:

==========================
External Simulation
==========================

.. note:: Feature requires a `Momentum Granular <https://www.algoryx.se/momentum-granular/>`_ license.

Simulations can be executed outside of **SpaceClaim/Algoryx Momentum** in a external **AGX Dynamics** environment to increase simulation performance. These external simulations can produce journal files, similar to those produced inside of SpaceClaim. The external journal files are loaded and post processed in the :ref:`journal_viewer`.

--------------------
Usage
--------------------

Click on the Simulate button in the External Simulation ribbon menu.

.. image:: ../images/en/ExternalSimulationRibbon.png

This opens up a dialog with different settings for the external simulation. See more in the Settings section below.

^^^^^^^^^^^^^^
Settings
^^^^^^^^^^^^^^

**Record Journal:** Specifies whether an external journal should be created from a simulation.

**Use Display Window:** Specifies whether a display window should be used in the external simulation.

**Computational threads:** Specifies the number of threads to be used in the simulation.

**Pause At:** Specifies the time stamp in seconds when the simulation should pause. You can press **e** to toggle pause/play mode during an active external simulation.

.. ATTENTION::
  The journal frequency of the recorded simulation will be the same as the document setting. See :ref:`Record Frequency <current_recording_frequency>`.

--------------------
Record Options
--------------------
Different properties of the particles can be selected to be recorded or not recorded into the journal. Fewer recorded properties will result in lower journal data size
but this also means that less information can be used in the post processing stage.

**Particle.velocity:** Particle velocity property.

**Particle.rotation:** Particle rotational property.

**Particle.color:** Particle color property.

**ParticlePairContact.localForce:** Contact forces between particles.

**ParticleGeometryContact.localForce:** Contact forces between particles and geometries.

.. ATTENTION::
  Recording contact forces is necessary for visualization of the granular contact network in :ref:`granular_postprocessing`.

.. image:: ../images/en/ExternalSimulation.png

Executing an external simulation by pressing *Launch Simulation* opens an `AGX Dynamics <http://www.algoryx.se/products/agx-dynamics/>`_ instance running the simulation in an external environment outside of **Algoryx Momentum**. This is done to increase the computational performance by skipping the overhead inside **Algoryx Momentum Granular** for large granular data sets.

.. ATTENTION::
  For systems with more than 10000 granular particles, it is recommended to run an external simulation.

.. image:: ../images/en/ESExample2.png